/* @(#) somx/readme 2.5 1/20/94 09:31:03 [5/15/94 17:57:48] */

/*
 * 96F8647, 96F8648, 96F8850 (C) Copyright IBM Corp. 1992, 1994
 * All Rights Reserved
 * Licensed Materials - Property of IBM
 *
 * DISCLAIMER OF WARRANTIES.
 * The following [enclosed] code is sample code created by IBM
 * Corporation. This sample code is not part of any standard or IBM
 * product and is provided to you solely for the purpose of assisting
 * you in the development of your applications.  The code is provided
 * "AS IS". IBM MAKES NO WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT
 * NOT LIMITED TO THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
 * FOR A PARTICULAR PURPOSE, REGARDING THE FUNCTION OR PERFORMANCE OF
 * THIS CODE.  IBM shall not be liable for any damages arising out of
 * your use of the sample code, even if they have been advised of the
 * possibility of such damages.
 *
 * DISTRIBUTION.
 * This sample code can be freely distributed, copied, altered, and
 * incorporated into other software, provided that it bears the above
 * Copyright notice and DISCLAIMER intact.
 */

NOTE:  Before attempting to build this sample, please read the readme file
       in samples/somd.

This directory contains the DSOM/C "Event Services" sample.  The Event Service
interface definitions are in eventch.idl and eventcom.idl.  The Event Service
sample program is based on the Consumer-Supplier paradigm for events.  The
Supplier generates events and pushes them onto an Event Channel.  The Consumer
polls the Event Channel and when an appropriate event appears, it is
processed.

In this sample, the Supplier updates the value of a spreadsheet cell and puts
the updated value in the Event Channel. The Consumer, which is polling the
Event Channel for a change in the cell value, pulls the new value from the
Event Channel and displays it.

The Consumer, in this example, picks up only the last update to the cell
value.  If the Supplier makes several cell updates between two Consumer
polling cycles only the latest value of the cell is passed onto the Consumer.


BUILDING THE SAMPLE
===================

The Makefile in this directory has been set up to build the example
Event Service program.

To erase all non-source files from the current directory, type "make clean"
("wmake /f makefile.wmk clean" on OS/2).

To build the example program, type "make" ("wmake /f makefile.wmk" on OS/2).

You can also make specific pieces of the example programs.  The following
targets have been defined in the Makefile:

   libevent.a (event.lib for OS/2) -- builds the DLL (dynamic link library) and
                  the compile-time "import library" for the example.

   eventsvr    -- builds the persistent Event Channel server

   eventcli    -- builds the client program which acts as a Supplier for events

   consumer    -- builds the Consumer part of the example.

   som.ir      -- builds the Interface Repository for the examples,
                  in a local file called "som.ir".  The Interface
                  Repository is a database containing all the interface
                  definitions for the classes in the library.

   somdimpl    -- builds the Implementation Repository for the examples,
                  at a location determined by the environment variable
                  SOMDDIR.  The Implementation Repository is a
                  database containing a description of a server
                  ("Ccellsvr") which will load the event.dll, and
                  will hold instances of the Cell and all Event Service
                  interface instances.

RUNNING THE SAMPLE
==================

To try out the sample, you must first start the DSOM daemon, "somdd" from
this directory. If the daemon is already running you must first kill it and
then restart it from this directory.

To start the daemon in the background, enter:

On AIX:

   somdd &

On OS/2:

   start /c /f somdd

To run the sample, you'll need three command entry windows.  Start two new
command entry windows in addition to the one you built the sample from,
and then follow the directions below. Remember that the DSOM environment
variables must be set with samples\somd\somdenv.csh or samples\somd\somdenv.sh
in the two new windows as well as the well as the one in which you built the
sample.

In the first window, run the event server program eventsvr:

   eventsvr Ccellsvr

From the second window start the client program eventcli:

   eventcli

From the third window start the Consumer program:

   consumer

Now, from the window running the Consumer program, press return (Enter) to
have the consumer process begin polling. It should immediately discover
a new cell value of 10. It will then prompt again to poll. Press return
to begin polling. Because the cell value has not yet been changed you will
continuously see the message "Event Channel yet to be notified".

Go to the window running the client program and press return in response to
the prompt "Increment cell value by 1?". The process will increment the
value of the cell, post the event and repeat the prompt. Note that the
consumer process has been notified of the update to the cell and has
displayed the new value of the cell.

You can continue to go back and forth between the client and the consumer to
experiment with the sample.

To terminate the sample programs, first quit out of eventcli and consumer by
typing 'q' or 'Q'. Then, terminate eventsvr by typing <ctrl-c> in the window
in which it is running and finally kill somdd.

